Add metadata support to callTool method #289

maeryo · 2025-09-24T12:48:32Z

According to https://modelcontextprotocol.io/specification/2025-06-18/basic/index#meta, the _meta parameter should be passable when calling tools. While the CallToolRequest class (in types.kt) currently includes _meta in its definition, SDK users cannot actually input _meta when invoking the callTool method.

This Pull Request adds a metadata parameter to the CallTool method and includes functionality to convert various data formats without loss.

Additionally, to encourage the use of valid Key name formats as defined by the protocol, validation for prefixes has been implemented.

kpavlov

Thank you @maeryo
PR should always come with a test.
Let's revisit it after #294 is merged, so we have all the models coming

kpavlov · 2025-09-29T07:19:44Z

kotlin-sdk-client/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/Client.kt

+        }
+
+    @OptIn(ExperimentalUnsignedTypes::class, ExperimentalSerializationApi::class)
+    private fun convertToJsonElement(value: Any?): JsonElement = when (value) {


It makes sense to extract JSON-related code to a separate class. It could be a separate PR with unit tests

Should be moved to separate class

maeryo · 2025-09-29T10:46:04Z

Thank you for your feedback, @kpavlov
I've committed the test code.
Is there anything else I should check?

kpavlov · 2025-09-29T12:17:07Z

Thank you, @maeryo
Mock transport is very valuable. Let's double-check that it is thread-safe and can be used for parallel tests, and extract it to separate file.
Please also run ktlint fix, because ette build is failing because of this

maeryo · 2025-09-29T13:34:59Z

@kpavlov, I just fixed ktlint. 🚀
Thank you!

devcrocod

Please take a look at my comments.
Also, it seems that your changes are breaking the tests

kotlin-sdk-client/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/Client.kt

devcrocod · 2025-10-22T20:52:22Z

Sorry, the integration tests broke because of the new field added. I’ll add a fix soon

maeryo · 2025-10-23T01:26:35Z

@devcrocod I've addressed all your comments. Please let me know if any further changes are needed.

- Add meta parameter support to callTool method with validation - Implement MCP-compliant meta key validation (reserved prefixes, format rules) - Enhance JSON conversion for complex data types with better error handling - Add comprehensive test suite for meta parameter functionality - Improve MockTransport to simulate proper initialization flow - Update API signatures to include meta parameter support

small refactoring

kpavlov · 2025-10-23T12:25:03Z

kotlin-sdk-client/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/Client.kt

-            Method.Defined.PromptsList,
-            Method.Defined.CompletionComplete,
-            -> {
+            Method.Defined.PromptsGet, Method.Defined.PromptsList, Method.Defined.CompletionComplete -> {


It's actually better to have each case on a new line, because add/delete is more visible in diff

kpavlov · 2025-10-23T12:26:06Z

kotlin-sdk-client/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/Client.kt

+        val labelPattern = Regex("[a-zA-Z]([a-zA-Z0-9-]*[a-zA-Z0-9])?")
+        val namePattern = Regex("[a-zA-Z0-9]([a-zA-Z0-9._-]*[a-zA-Z0-9])?")


Regex patterns should be static constants

kpavlov · 2025-10-23T12:27:52Z

kotlin-sdk-client/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/Client.kt

+        }
+
+    @OptIn(ExperimentalUnsignedTypes::class, ExperimentalSerializationApi::class)
+    private fun convertToJsonElement(value: Any?): JsonElement = when (value) {


Should be moved to separate class

kpavlov · 2025-10-23T12:28:58Z

.../kotlin/io/modelcontextprotocol/kotlin/sdk/integration/kotlin/AbstractToolIntegrationTest.kt

                  "formattedResult" : "11,000",
                  "precision" : 3,
-                  "tags" : [ ]
+                  "tags" : ["test", "calculator", "integration"]


👍🏻 something was fixed

Yes, previously the arrays were serialized as a string, and for some reason they were completely skipped in the process

kpavlov · 2025-10-23T12:33:20Z

...t/src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/client/ClientMetaParameterTest.kt

+            client.callTool("test-tool", mapOf("arg" to "value"), validMeta)
+        }
+
+        assertTrue(result.isSuccess, "Valid meta keys should not cause exceptions")


assertion for meta content is missing

kpavlov · 2025-10-23T12:34:38Z

...t/src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/client/ClientMetaParameterTest.kt

+    }
+}
+
+class MockTransport : Transport {


MockTransport should be moved to separate file. It's a nice reusable stuff

kpavlov · 2025-10-23T12:35:19Z

...t/src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/client/ClientMetaParameterTest.kt

+}
+
+class MockTransport : Transport {
+    private val _sentMessages = mutableListOf<JSONRPCMessage>()


not a thread-safe collection

kpavlov · 2025-10-23T12:35:57Z

...t/src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/client/ClientMetaParameterTest.kt

+    }
+
+    override fun onMessage(block: suspend (JSONRPCMessage) -> Unit) {
+        onMessageBlock = block


should also capture and expose received messages (thread-safe)

kpavlov

Thank you, folks!
I'm fine with merging this PR and making betterments in follow-up PR(s)

maeryo · 2025-10-23T12:55:59Z

@kpavlov Thanks for all the feedback. I'll prepare a follow-up PR after this is merged.

… in tests

## Changes - Updated `DecimalFormatSymbols` to use period as decimal separator (Locale.US) - Fixed test expectations in `testComplexInputSchemaTool`: - `formattedResult`: `"11,000"` → `"11.000"` - `tags`: Added actual test values `["test", "calculator", "integration"]` - Fixed test expectations in `testComplexNestedSchema`: - `formattedResult`: `"0,00"` → `"0.00"` ## Motivation 1. **Standard Decimal Notation**: Using a comma as a decimal separator could be confusing as it's commonly used for thousands separators in many locales. Standardizing on the period (`.`) follows international conventions and makes the output clearer. 2. **Test Data Correction**: During the Validate PR workflow for #289, discovered that the `tags` array in the `expectedContent` variable of `testComplexInputSchemaTool()` was incorrectly set to an empty array, which didn't match the actual input values being tested. --------- Co-authored-by: MAERYO <[email protected]>

maeryo mentioned this pull request Sep 24, 2025

Expose RequestParams._meta in ClientSession.call_tool modelcontextprotocol/python-sdk#1231

Merged

9 tasks

kpavlov reviewed Sep 29, 2025

View reviewed changes

kpavlov added the question Further information is requested label Sep 29, 2025

maeryo mentioned this pull request Oct 11, 2025

Fix decimal separator format in calculator tool tests #315

Merged

devcrocod force-pushed the add-meta-in-call-tool-method branch from 5a73759 to 2b957a9 Compare October 22, 2025 20:10

devcrocod requested changes Oct 22, 2025

View reviewed changes

MAERYO and others added 7 commits October 23, 2025 14:12

feat: Add meta parameter support to callTool method

ad37e5d

feat: implement complete _meta support with MCP specification validation

e6e5d54

fix: correct _meta key validation according to MCP spec

135ffd7

test: add comprehensive meta parameter tests for callTool

b9b3ba2

refactor: simplify validation and JSON conversion

4a1a29e

Fix compilation and tests for meta.

7e087b4

small refactoring

devcrocod force-pushed the add-meta-in-call-tool-method branch from 127b270 to 7e087b4 Compare October 23, 2025 12:14

devcrocod requested review from devcrocod and kpavlov October 23, 2025 12:14

devcrocod previously approved these changes Oct 23, 2025

View reviewed changes

kpavlov reviewed Oct 23, 2025

View reviewed changes

kpavlov previously approved these changes Oct 23, 2025

View reviewed changes

kpavlov added the bugfix Something was fixed 🎉 label Oct 23, 2025

Add MockTransport for testability and improve meta field validation…

de5f8b5

… in tests

devcrocod dismissed stale reviews from kpavlov and themself via de5f8b5 October 23, 2025 13:03

kpavlov approved these changes Oct 23, 2025

View reviewed changes

devcrocod merged commit 407df7a into modelcontextprotocol:main Oct 23, 2025
3 checks passed

kpavlov mentioned this pull request Oct 23, 2025

Refactor MockTransport #333

Open

11 tasks

maeryo mentioned this pull request Oct 23, 2025

Follow-up improvements for #289 and #333 #335

Open

10 tasks

		val labelPattern = Regex("[a-zA-Z]([a-zA-Z0-9-]*[a-zA-Z0-9])?")
		val namePattern = Regex("[a-zA-Z0-9]([a-zA-Z0-9._-]*[a-zA-Z0-9])?")

Add metadata support to callTool method #289

Add metadata support to callTool method #289

Uh oh!

Conversation

maeryo commented Sep 24, 2025

Uh oh!

kpavlov left a comment

Choose a reason for hiding this comment

Uh oh!

kpavlov Sep 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

maeryo commented Sep 29, 2025

Uh oh!

kpavlov commented Sep 29, 2025

Uh oh!

maeryo commented Sep 29, 2025

Uh oh!

devcrocod left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

devcrocod commented Oct 22, 2025

Uh oh!

maeryo commented Oct 23, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kpavlov left a comment

Choose a reason for hiding this comment

Uh oh!

maeryo commented Oct 23, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kpavlov Sep 29, 2025 •

edited

Loading